Description

The hypsometric formula for altitude calculation uses the specific gas constant for dry air (287.05 J/(kg·K)), which underestimates altitude in humid conditions. Moist air is less dense than dry air at the same T and P because water vapor (~18 g/mol) is lighter than dry air (~29 g/mol).

Added optional relativeHumidity parameter that applies virtual temperature correction when provided.

Type of Change

• New formula/feature (non-breaking change that adds functionality)
• Documentation update

Related Issue

Fixes #(research-altitude-from-pressure-difference)

Changes Made

• Added optional relativeHumidity parameter (0-100%) to altitudeFromPressureDifference
• Implemented virtual temperature approach using existing library functions (saturationVaporPressure, actualVaporPressure, mixingRatio, virtualTemperature)
• Added 6 tests covering moist air scenarios
• Updated JSDoc and README

Formula Details (if applicable)

Formula Name

Hypsometric Equation with Virtual Temperature Correction

Scientific Source

• Source: Virtual Temperature in Hypsometric Equation
• Link: https://en.wikipedia.org/wiki/Virtual_temperature

Input Parameters

• referencePressure - Reference pressure (Pa)
• observedPressure - Observed pressure (Pa)
• referenceAltitude - Reference altitude (m), default 0
• temperature - Average temperature (K), default 288.15
• relativeHumidity - Optional relative humidity (%), 0-100

Output

• Altitude in meters (m)

Validation

• Tested against known reference values
• Compared to scientific literature

Testing

Test Coverage

• Added tests for new functionality
• All tests pass locally (npm test)
• Build succeeds (npm run build)

Test Results

Tests:       221 passed, 221 total (6 new tests)

Manual Testing

// Dry air: ~1011 m
altitudeFromPressureDifference(101325, 89874, 0, 288.15);

// 60% RH: ~1021 m (~1% higher due to lower moist air density)
altitudeFromPressureDifference(101325, 89874, 0, 288.15, 60);

Documentation

• Updated README.md (if needed)
• Added/updated JSDoc comments
• Added usage examples (if applicable)

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published
• I have used the correct units (Kelvin for temperature, SI units for others)
• I have verified backward compatibility (or documented breaking changes)

Breaking Changes

• This PR introduces breaking changes
• I have updated the version number appropriately

Details of breaking changes:
N/A - fully backward compatible. Omitting relativeHumidity produces identical results.

Screenshots (if applicable)

N/A

Additional Notes

• Effect magnitude: ~1% at 15°C/60% RH, larger at higher temps, minimal below freezing
• Uses geometric mean of pressures for mixing ratio (exponential pressure profile)
• Reuses existing virtualTemperature() from temperature.ts

Performance Impact

• No performance impact

Details:
Additional calculations only when relativeHumidity is provided.

Dependencies

• No new dependencies

Reviewer Notes

• Key files to review: src/formulas/altitude.ts
• Areas needing special attention: Virtual temperature calculation logic (lines 69-89)
• Questions for reviewers: Is geometric mean the preferred approach for average pressure, or should arithmetic mean be considered?

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.